******* fMSX ******* The Portable MSX/MSX2/MSX2+ Emulator version 1.5 by Marat Fayzullin email: fms@freeflight.com IRC: RST38h WWW: http://www.freeflight.com/fms/ * NEW IN THIS VERSION * o More stable split screen (Zanac-Ex no longer blinks) o RAM mapper fixed *again* (Designer+ works now) o V9938 SRCH command fixed o MSXDOS2.ROM support o PAINTER.ROM support o FMPAC.ROM support o .PSG file format is updated o Serial port support is *not* yet implemented. * INTRODUCTION * Please, *carefully* read this manual. Do not write me email with questions answered in here, as such letters are going to be ignored: I have too many other things to do to answer the same questions over and over again. *Developers*, there is a special section for you below. .PSG file format has got some additions again. fMSX is a portable emulator of MSX home computers written in C. You can always get the latest fMSX source code, binaries, and support files from http://www.freeflight.com/fms/fMSX/ Another MSX-related archive is located at ftp://altair.komkon.com/pub/MSX/ There are versions of fMSX for Amiga, Macintosh, IBM PC (both MeSsyDOS and Windoze), and other systems. Following people are maintaining ports of fMSX to these systems: Amiga: Hans Guijt [jguijt@WI.LeidenUniv.NL] MSDOS: Marcel de Kogel [m.dekogel@student.utwente.nl] Alex Krasivsky [al@ares.iki.rssi.ru] Igor Sharfmesser [igor@asni.itpm.alma-ata.su] Windows: Marat Fayzullin [fms@freeflight.com] Tekuro Tokuyama [94i23@ieee.hokudai.ac.jp] Macintosh: John Stiles [jstiles@cello.gina.calstate.edu] Paul Chapman [pchapman@cs.stmarys.ca] PC9801: Murakami Reki [90315054@ex.ecip.osaka-u.ac.jp] If you would like to port fMSX to another system, or make changes in fMSX's code *please*, contact me by email or some other means. Note, that fMSX source code is freely distributable, but it is *not* public domain. You can not use it in commercial purposes unless you contact me to arrange the conditions of such usage and get my permission. Feel free to look at existing drivers as well as at other code. More explanations follow. This manual covers two different fMSX distributions: 1. *** Source Code Distribution *** This distribution includes C sources for a portable MSX emulator, and screen/keyboard drivers for Unix/X and MSDOS. fMSX has been tested on following Unix systems: NetBSD FreeBSD Linux SunOS Solaris OSF/1 Ultrix Irix AIX HP-UX 2. *** fMSX-Windows Distribution *** Due to the flood of requests from the people who use DOS/Windows running PCs and are unable to compile the emulator on their own, I have ported fMSX under Microsoft Windows. This distribution contains an executable of a limited version of fMSX-Windows which doesn't allow you to use the second cartridge slot and the second disk drive, and has an annoying "fMSX DEMO" message across its window. The uncrippled version of fMSX-Windows is available for $35US from Marat Fayzullin 6304 Hampton Place Elkridge, MD 21227 USA fMSX-Windows is a 32-bit application which runs under Windows 95, and Windows NT. It is compiled with Borland C++ and needs Microsoft WinG library which can be obtained from ftp://ftp.microsoft.com/Softlib/MSFILES/WING10.EXE There is also another Windows port available from Teturo Tokuyama. It is *free*, but not up-to-date, and lacks many features. Both versions use the same MIDI sound drivers written by Teturo. * IMPORTANT NOTES FOR DEVELOPERS * o The format of fMSX soundtrack files consists of a 16-byte header followed by a sequence of records: Header: 0-2 "PSG" 3 ^Z (1Ah) 4 Version Number (10h) 5 Interrupt Frequency, Hz 6-15 00h 00h 00h 00h 00h 00h 00h 00h 00h 00h Record Type 1: (an interrupt mark) DB FFh Record Type 2: (multiple interrupt marks) DB FEh DB Number Record Type 3: (a write to a PSG register) DB Register - Register number DB Value - Value to write When Register>15, a write into SCC register #(Register-16) is assumed. Those who do not implement SCC may simply skip such records. When Register>159, a write into FM-PAC (OPL2) register is assumed. Those who do not implement FM-PAC may simply skip such records. * SHORT MANUAL FOR THE WINDOWS USERS * In order to use fMSX-Windows, you will first have to install WinG graphical library which can be obtained from Microsoft (see address above). Borland's BWCC32.DLL is *no longer needed*, although you do need to have Windows95 in order to run fMSX (3.xx will not do). All options are stored in the FMSX.INI file. Unregistered version does not support .INI file though, so you won't be able to store any options in it. fMSX-Windows runs in a resizable window with the following menus: o File o New This opton allows to restart fMSX with a new cartridge in slot A. o Setup This option pops up a setup dialog allowing to change emulation parameters: o Cart A and B You can set the names of .ROM files to be used as cartridges in slots A and B using these options. Notice that slot B is *disabled* in the unregistered version of fMSX-Windows. This option will only take effect after fMSX is restarted. o Disk A and B You can set the names of .DSK files to be used as floppies in drives A and B using these options. Notice that drive B is *disabled* in the unregistered version of fMSX-Windows. Read FAQ section below to find out more about using disks with fMSX. This option will only take effect after fMSX is restarted. o Font Using this option, you can set the .FNT file from which the external font will be taken (See "Use External Font" below). This option will only take effect after fMSX is restarted. o Tape Using this option, you can set the .CAS file which is used as a casette tape. This option will only take effect after fMSX is restarted. o Hardware Version This set of radioboxes allows you to select a version of MSX you want to emulate. THe original MSX requires MSX.ROM to be present in the current directory. MSX2 needs MSX2.ROM and MSX2EXT.ROM, while MSX2+ requires MSX2P.ROM and MSX2PEXT.ROM. o MegaROM Type If you are playing a game from a MegaROM cartridge (>32kB), these radioboxes are used to select the MegaROM mapper type. There is no simple way to say which type each particular game requires, so you will have to try all of them. All Konami games using SCC chip are of type Konami5 though, while all Konami MegaROMs without SCC chip are of type Konami4. o Use External Font If this checkbox is checked, text screens will use an external 8x8 font loaded from a given file instead of MSX's own font contained in MSX VRAM. This may be useful in Russia where people may want to use KOI8 font while running fMSX on the "european" ROMs, in Japan, and other countries which used localized models of MSX. o Automatic Fire When you check this checkbox, the space bar will generate multiple keypresses while you hold it down. This option is useful in games and plays the role of "joystick autofire". o Save CPU When this checkbox is checked, fMSX will "fall asleep" when its window is iconized or deactivated. In this mode, no CPU cycles are spent, and the emulation is paused. It may be useful for those who want to pause a game, do some work and then return to the game and those who run extensive computations in background and don't want to tie up the CPU. o Interrupt Period This parameter determines how many CPU commands will be executed between vertical blanking interrupts. Setting it lower may speed up the emulation, but setting it too low will hang it. o Update Period This parameter determines how many vertical blanking interrupts will pass between window refreshes. It is usually set to 2, but you can increase it to make fMSX work faster. The sprite movements become jerky at high update periods though, and some sprites may simply disappear. o Reset By pressing this button, you restart fMSX with the new emulation parameters (cartridge, disk, and font files). o Quit Quit the emulation. CMOS.ROM file will be saved on exit, if CMOS was changed (with SET command, for example). o Size o 1:1 These options change the window size to be the same as in real o 2:1 MSX, or 2/3 times bigger. Please, note that you can change o 3:1 window size by simple dragging the bottom-right corner of a window with the mouse. Also, the 512-pixel wide screen modes require at least 2:1 size to show up correctly. o Help o About This option will display a dialog box with copyright information and other legal stuff. * FREQUENTLY ASKED QUESTIONS * 1. What is MSX? MSX is an old Z80-based family of home computers which appeared in 1982 as an attempt to establish a single standard in home computing similar to VHS in video. They were popular in Asian (Korea, Japan) and South American (Brazil, Chile) countries as well as in Europe (Holland, France) and former Soviet Union, but they are virtually unknown in USA. Although MSX standard quietly died to year 1988, the world got to see MSX2, MSX2+ and TurboR extensions of it. In spite of its sad history, MSX is a very nice computer, especially useful for educational purposes which is clearly indicated by example of the Soviet Union. Russian Ministry of Education bought hundreds of MSXes (and later MSX2s) grouped into "computerized classroom systems" of 10-16 machines interconnected by a simple network. Entire generation of programmers has grown up using these computers. Hardware-wise, MSX represents a hybride of a Nintendo Entertainment System and a generic CP/M-80 machine. Its heart is Z80 CPU working at 3.58MHz in the base model (frequency was doubled in TurboR). The video subsystem is built around TI9918 or TI9928 VDP chip also used in Texas Instruments' TI-99/4 computers. In the later MSX models this chip was upgraded to V9938 (MSX2) and V9958 (MSX2+ and TurboR). The latest version is V9990. The audio system is handled by AY-3-8910 chip by General Electric, same as the one used in Sinclair ZXSpectrum128 audio. AY-3-8910 provides 3 channels of synthetized sound, noise generation, and two general purpose parallel IO ports which are used for joysticks and some other things in the MSX design. Due to their hardware structure, MSX machines were perfectly suitable for games and there is a lot of good games either written or ported to them. You can find more information about MSX and remaining MSX fans at http://freeflight.com/fms/MSX/ 2. Where do I get MSX software? ftp://ftp.komkon.org/pub/MSX/ ftp://ftp.funet.fi/pub/msx/ ftp://riaph.irkutsk.su/pub/ ftp://ftp.saitama-u.ac.jp/pub/msx/ 3. What do I do with .BAS,.GMB,.CRC,.LDR files? These are BASIC programs. You run them from MSX BASIC with RUN "filename" 4. What do I do with .BIN,.OBJ,.GM files? These are so-called BLOADable binary files. They can be run from MSX BASIC with BLOAD "filename",R 5. What do I do with .COM files? These are MSX DOS command files. Boot MSX DOS and run them from there. 6. What are the .ROM files? .ROM files are the binary images of cartridge ROMs which can be loaded into fMSX. There are "standard" cartridge ROMs which are 16kB or 32kB big, and the MegaROMs which can be 128kB, 256kB and even 512kB. Latter require a special MegaROM-Mapper feature of fMSX which can be adjusted with -rom options. 7. What are the .ROM files included with fMSX? Following are the files used by fMSX: MSX.ROM - Standard MSX BIOS and BASIC code MSX2.ROM - MSX2 BIOS and BASIC code MSX2EXT.ROM - MSX2 ExtROM containing system extensions MSX2P.ROM - MSX2+ BIOS and BASIC code MSX2PEXT.ROM - MSX2+ ExtROM containing system extensions DISK.ROM - MSX DiskROM containing BDOS and DISK BASIC (optional) RS232.ROM - RS232 BIOS and BASIC extensions (optional) FMPAC.ROM - FM-PAC BIOS and BASIC extensions (optional) MSXDOS2.ROM - MSXDOS2 system core (optional) PAINTER.ROM - Yamaha Painter, graphical editor found in Russian MSX machines from Yamaha (optional) CMOS.ROM - Non-volatile memory used in MSX2 and MSX2+. This file gets rewritten on exit if non-volatile memory was changed. 8. How do I use disks with fMSX? fMSX includes disk support starting with version 0.9. If you have an earlier version, you can not use disks. The following instructions assume that you have a version including the disk support. First, make sure that the DISK.ROM file containing MSX DiskROM is in the current directory. Then, use an MSDOS program called DCOPY.EXE to create disk images of your MSX disks: DCOPY : .DSK The images are just raw files with all disk blocks written in a sequence. They can also be created on a Unix machine with cp /dev/rfd0 .DSK or a similar command. If you have a 1.44MB HD floppy formatted on MSX for 720kB, don't forget to stick a piece of tape on the HD/DD indicator hole. After you have created disk image files, run fMSX in the following way: fmsx -diska .DSK -diskb .DSK where two image filenames will become your drives A: and B:. You can also have default disks called DRIVEA.DSK and DRIVEB.DSK and located in the current directory. 9. Where is the complete list of command line options of fMSX? Use -help option. It will tell fMSX to display all options available in your version. Following are the currently available options: -verbose - Select debugging messages [1] 0 - Silent 1 - Startup messages 2 - V9938 ops 4 - Disk 8 - Memory 16 - Illegal Z80 ops -ifreq - Set external interrupts frequency [off] -iperiod - Set internal interrupts period [6000ops] -uperiod - Number of interrupts per screen update [2] -help - Print this help page -printer - Redirect printer output to file [stdout] -shm/-noshm - Use/don't use MIT SHM extensions for X [-shm] -ram - Number of 16kB RAM pages [4/8/8] -vram - Number of 16kB VRAM pages [2/8/8] -trap
- Trap execution when PC reaches address [FFFFh] -msx1/-msx2/-msx2+ - Select MSX model [-msx1] -rom - Select MegaROM mapper types [0,0] (two -rom options can be present) 0 - Konami 8kB 1 - Konami 16kB 2 - Konami5 8kB 3 - Konami4 8kB 4 - ASCII 8kB 5 - ASCII 16kB -diska - Set disk image used for drive A: [DRIVEA.DSK] -diskb - Set disk image used for drive B: [DRIVEB.DSK] -font - Set fixed font for text modes [DEFAULT.FNT] -serial - Redirect serial I/O to a file [stdin/stdout] -logsnd - Write soundtrack to a file [off] -saver/-nosaver - Save/don't save CPU when inactive [-saver] -sound/-nosound - Play/don't play sound [-nosound] 10. What are the keys used in fMSX? Unix version: F6 - HOME/CLS F7 - DEL F8 - INS F9 - SELECT F10 - STOP F11 - Trace on/off [DEBUG] F12 - Exit F13 - Turn fixed font on/off in the text modes RSHIFT - CAPS Lock ALT - GRAPH Windows version: Insert - INS Delete - DEL Home - HOME/CLS End - SELECT PageUp - STOP PageDn - GRAPH CpsLck - CAPS Lock F12 - National Alphabet (Cyrillic, Kana, etc.) 11. Why is the emulator so slow on my PC? Because your PC is too slow to run it. The emulator is written entirely in C language and therefore is quite slow. Although it works on 486/33 and even 386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can try to speed it up by increasing -uperiod value controlling the number of interrupts between screen updates to 3-6, and by decreasing -iperiod value controlling the number of CPU cycles between interrupts to 2000-5000. 12. Can I compile the emulator with my Borland/Turbo C compiler? You can, given that your compiler creates executables using flat 32bit memory model. Two PC compilers which do that are WATCOM (using DOS4GW DOS extender) and GCC (using DJPP extender). The only 32bit Borland/Turbo C compiler that I'm aware is for Windows though. 13. I can't get some ROM images to work with the emulator. Try increasing -iperiod value to 10000 and higher. If the ROM image is bigger than 32kB, try using -rom parameter with different s (see fmsx -help for the complete list). If you can't get ROM image to work, send it to me for analysis. 14. Is it legal to spread cartridge ROMs? NO. Nobody seems to care though, mainly because there is no profit to be made on these ROMs any longer. Nevertheless, be aware of the fact that by using commercial software you haven't bought, you are commencing an act of piracy. Not that I care, anyway... 15. When compiling emulator under Unix, I get "undefined name" errors. This means that your linker can not find the libraries necessary for the emulator (namely, libX11.a and libXext.a) or some additional libraries (like libsocket.a and libnsl.a) are required. Find these libraries in your system and modify the Makefile so that the final invocation of the C compiler has "-L" options. If you have no libXext.a library, try #undefining MITSHM option. 16. When starting emulator under Unix, I get X_ShmAttach error. You are probably trying to run the emulator on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use -noshm option to tell it not to use shared memory. 17. The emulation starts under Unix, but then I get X_PutImage error. Unix/X version of fMSX currently needs 256-color X. Neither 2-color nor TrueColor Xterminals will work with the drivers included into "official" fMSX distribution. Arnold Metselaar (metselr@fys.ruu.nl) developed the drivers supporting any Xterminal. These drivers are available at http://www.fys.ruu.nl/~metselr/X-drivers.html 18. I start the Unix version of the emulator but the window stays black. Some other X application took over all available colors so that the emulation could not allocate any for itself. Check if you run XV, Netscape, or something similar. 19. How can I get sound in fMSX? The Unix/X version has no sound yet, although there are some works going on in this direction. In the "official" DOS version, use -adlib option. Your soundcard should be SoundBlaster-compatible though. The Windows versions of fMSX produce sound via General MIDI Interface which has to be set up in order to get sound. 20. I get distorted colors in fMSX-Windows. You are probably running Windows in 256-color mode. In this mode, not all of 256 colors are accessible as some of them are taken over by other programs. Therefore, the system is trying to pick the closest possible colors, which do not always look right. Switch Windows into 16bit or 24bit colors mode for the right colors. * COMPILATION TIPS * If you are compiling the emulator under Unix, use Makefile. Notice that #define UNIX is present in this case. The emulation is written in fairly portable C code and may therefore be compiled with any decent ANSI C compiler. It relies on a flat 32bit memory model though, so Borland compilers will choke on it. Standard CC or GCC should do the job under Unix, although beware of GCC code generation bugs. If you are working under MeSsyDOS, use WATCOM C which is known to work. Under (God prohibits) Windows, use Borland C++ which has 32bit compilation model. On Amiga, use SAS/C. On Macintoshes, use Metrowerks C. If you are using an Intel-based computer or any other machine which has least-significant-byte-first data layout (for example, DEC Alpha), insert #define LSB_FIRST in the beginning of Z80.h file. The emulator will not work otherwise. If you put #define DEBUG in the beginning of Z80.h, the emulator will print debugging information about CPU registers after executing each command. You can turn debugging on and off by setting Trace variable to 1 and 0 accordingly. Also, by setting Trap variable to some address you will make it start tracing when PC reaches this address (-trap option). When you port the program to a new machine, you have to write a set of drivers for keyboard, sprites, and all the screen modes you want to emulate. The emulator comes with a set of drivers for XWindows system. The common code for these drivers is located in Common.h and can be used for other systems too. Screen drivers use simple XSIZE*YSIZE array of bytes to generate image, so in most cases you will only need to adjust these drivers to your own needs. Note that the X11 drivers use so-called MIT Shared Memory Extension for fast transfers from buffer to a window. If you do not have MIT SHM extension in your system, remove #define MITSHM You can also turn MITSHM off (for example, if you use remote X terminal) by setting UseSHM variable to 0 before starting the emulation (-noshm option). * CODE STRUCTURE * Several other variables control the behaviour of the emulator. All of them should be set before starting the emulation in order to take effect: Verbose = 0..31 Defines amount of debugging information printed by emulator. Default value is 1. Each bit of this variable enables printing of some kind of debugging info (VDP,CPU,memory,etc.). IPeriod = 1000..50000 Defines how many CPU commands should be executed between two interrupts. Normal interrupt rate is 60Hz for NTSC systems or 50Hz for PAL systems. Default value of IPeriod is 6000. CPURunning = 0/1 Set this variable to 0 to stop CPU and exit the emulation. Trace = 0/1 Print debugging information about CPU state. Default value is 1. #define DEBUG should be present in order to use this option. Tracing can be turned on and off during execution, for example, in keyboard driver. Trap = 0x0000..0xFFFF Automatically start tracing when PC reaches given address. #define DEBUG should be present in order to use this option. UPeriod = 1..10 Defines how many interrupts should pass between two consequent screen updates. Default value of UPeriod is 2. UseFont = 0/1 Use external font taken from the FontName file, Default value is 0. Printer = "printer.out" Name of file to output data sent to MSX printer. Default value of this variable is NULL which causes fMSX to "print" to stdout. CartA = "cartridge.file" Name of a .ROM file to load into Slot 1. Default value is "CARTA.ROM". This variable is ignored if no file exists. CartB = "cartridge.file" Name of a .ROM file to load into Slot 2. Default value is "CARTB.ROM". This variable is ignored if no file exists. DiskA = "diskimage.file" Name of disk image to use for drive A:. Default value is "DRIVEA.DSK". This variable is ignored if no file exists. DiskB = "diskimage.file" Name of disk image to use for drive B:. Default value is "DRIVEB.DSK". This variable is ignored if no file exists. FontName = "font.file" Name of the font to be used in text modes. Default value is "DEFAULT.FNT". This variable is ignored if no file exists. ROMTypeA = 0..5 MegaROM mapper type for cartridge in Slot 1. ROMTypeB = 0..5 MegaROM mapper type for cartridge in Slot 2. RAMPages = 4..16 Number of 16kB RAM pages to use. MSX1 needs 4 RAM pages. MSX2 needs 8 RAM pages which are accessible via mapper. VRAMPages = 2..8 Number of 16kB VRAM pages to use. MSX1 needs 2 VRAM pages. MSX2 needs 8 VRAM pages. UseSHM = 0/1 Use MIT SHM extension in X11 screen drivers. Default value is 1. #define MITSHM should be present in order to use this option. In order to run the emulation: 1. Set all necessary variables. 2. Initialize screen and keyboard drivers. In the case of X11 drivers, it is done by calling InitMachine() implemented in Unix.c and returning 1 on success or 0 otherwise. 3. Call StartMSX(). 4. Call TrashMSX(). 5. Shut down screen and keyboard. In X11 case, by calling TrashMachine(). 6. Exit the program. Take a look at fMSX.c to see an example of a sequence explained above. * THANKS TO... * o Hans Guijt [.NL] Working on Amiga port, Hans has done a very good job in getting fMSX run fast on an Amiga. He rewrote the CPU emulation and the screen drivers in assembler, optimized the VDP emulation, wrote sound drivers, and added many more things making fMSX-Amiga the best, if not the fastest MSX emulator for this platform. Thanks, Hans (and yes, I do remember those .ROM files too ;)). o Igor Sharfmesser [.KZ] and Alex Krasivsky [.RU] Igor and Alex has brought to life fMSX-MSDOS. The first version, including screen and keyboard drivers, was done by Igor. AdLib sound was added by Alex. The development is done using WATCOM C. o Teturo Tokuyama [.JP] Teturo has done an excellent port of fMSX to Windows. As much as I hate MeSsyWindoze, I must admit that Teturo's fMSX-Win32 with its resizable window and the drivers partially rewritten in assembly language rules. Period. o Murakami Reki [.JP] Murakami has written PC9801 port of fMSX. He is the guy whom you have to thank for the disk support in fMSX. If not for him, I wouldn't ever started implementing it :). o Marcel de Kogel [.NL] Marcel wrote an excellent port of fMSX to DOS, taking over the DOS ports development for ColEm and VGB too. His DOS version of fMSX is actually the first one which works right in all aspects. Marcel also provided invaluable help debugging and improving fMSX and other emulators. o Ville Hallik [.EE] AY8910 and SCC chips emulation, written by Ville for Linux/FreeBSD /dev/dsp device, and SunOS /dev/audio, is the best fMSX sound emulation I have heard so far. And, yes, it lets you play MSX games with sound on a Unix system! =:) o John Stiles [USA] John took over the development of the Macintosh version of fMSX and managed to speed up the common part of display drivers used in the Unix/X,DOS,Windows, and Macintosh versions. o Paul Chapman [.CA] Paul Chapman is the author of fMSX-MAC/PowerMAC. Although his program has bugs, it looks great and works faster than the original MSX computer on an average PowerMAC. As Paul is not able to develop fMSX-MAC actively at this moment, he has given me the source code which I put onto fMSX WWW page. o Arnold Metselaar [.NL] If you happen to have a non-256-color X11 display, get Arnold's X11 drivers fixed to work for any screen depth. o Guenter Woigk [.DE] Found a bug with offsets in Z80 commands using IX/IY registers. o Martial Benoit [.FR] Explained how VDP deals with sprites and sent me copies of V9938 and WD2793 databooks (WOW! Thanks, Martial :)). o Alex Wulms [.NL] Sent me a copy of WD1793 databook. o Maarten Huurne Has done some extensive bug-hunting on the Solid Snake cartridge ;). ...and to all of .NL/.CL/.SU people who helped me with advices, information, and encouragment. ENJOY THE EMULATOR AND LET US KEEP MSX ALIVE :) Marat.